home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 October: Mac OS SDK / Dev.CD Oct 96 SDK / Dev.CD Oct 96 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODFDev / ODF / Found / FWString / Include / SLStrRep.h < prev    next >
Encoding:
Text File  |  1996-08-16  |  14.3 KB  |  352 lines  |  [TEXT/MPS ]
  1. //========================================================================================
  2. //
  3. //    File:                SLStrRep.h
  4. //    Release Version:    $ ODF 1 $
  5. //
  6. //    Copyright:    (c) 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  7. //
  8. //========================================================================================
  9.  
  10. #ifndef SLSTRREP_H
  11. #define SLSTRREP_H
  12.  
  13. #ifndef SLLOCALE_H
  14. #include "SLLocale.h"
  15. #endif
  16.  
  17. // Export or Import functions for CFM-68K [sfu]
  18.  
  19. #if defined(FW_ODFLIB_IMPORT)
  20. #pragma import on
  21. #elif defined(FW_ODFLIB)
  22. #pragma export on
  23. #endif
  24.  
  25. FW_EXTERN_C_BEGIN
  26.  
  27. // NOTES
  28. //
  29. //    StringReps are reference counted, so they are always heap allocated.
  30. //    This allows us to make them be an opaque data structure.
  31. //    Since they are opaque, ALL access is through accessor functions.
  32. //    This means that storage allocation is under complete control
  33. //    of the SLStrRep subsystem.
  34.  
  35. //========================================================================================
  36. //    Forward Declarations
  37. //========================================================================================
  38.  
  39. struct ODIText;
  40.  
  41. //========================================================================================
  42. //    STRUCT FW_SPrivStringRep
  43. //========================================================================================
  44.  
  45. struct FW_SPrivStringRep;
  46.     // An opaque data structure!
  47.     
  48. typedef FW_SPrivStringRep* FW_HString;
  49.     // A handle to a string. The preferred way to reference a PrivStringRep
  50.  
  51. //----------------------------------------------------------------------------------------
  52. //    FW_StringLength
  53. //----------------------------------------------------------------------------------------
  54.  
  55. // FW_ByteCount FW_StringLength(const char* string);
  56.     // Search for the NUL termination, return number of bytes.
  57.  
  58. //========================================================================================
  59. //    FW_SPrivStringRep Member Functions
  60. //========================================================================================
  61.  
  62. FW_HString FW_PrivString_AcquireEmptyString();
  63.     // Returns a rep for an empty (roman, english) string.
  64.     // The rep is shared by all empty strings.
  65.  
  66. FW_HString FW_PrivString_AcquireEmptyStringWithLocale(FW_Locale locale, FW_PlatformError* error);
  67.     // Returns a rep for an empty string from specified locale.
  68.     // This always creates a new rep.
  69.  
  70. void    FW_PrivString_Acquire(FW_HString self);
  71.     // Increments the reference count
  72.  
  73. void    FW_PrivString_Release(FW_HString self);
  74.     // Decrements the reference count.
  75.     // If the reference count is zero, the client will probably want
  76.     // to immediately call FW_PrivString_Delete, though the call
  77.     // may be deferred if the client wants to reuse the structure.
  78.     
  79. FW_HString FW_PrivString_LockString(FW_HString self, FW_PlatformError* error);
  80.     // Locks the string (if not already locked) and returns the locked rep.
  81.  
  82. FW_HString FW_PrivString_NewRepWithStaticBuffer(unsigned char* buffer,
  83.                                     FW_ByteCount bufferLen);
  84.     // Allocate a new rep that uses the given static buffer
  85.     // This function may fail due to insufficient memory, if so NULL is returned.
  86.     // No error code is returned because the intention is that this function
  87.     // is to only be called from a constructor's initializer list
  88.  
  89. void FW_PrivString_ReleaseStaticBuffer(FW_HString self, FW_PlatformError* error);
  90.     // Release use of a static buffer.
  91.  
  92. void FW_PrivString_Retrieve(FW_HString self, 
  93.             char* destination, 
  94.             FW_ByteCount numberChars, 
  95.             FW_BytePosition position);
  96.     // Retrieve a range of bytes from the string, placing them in destination.
  97.  
  98. FW_HString FW_PrivString_Delete(FW_HString self, 
  99.             FW_ByteCount numberBytes, 
  100.             FW_BytePosition position, 
  101.             FW_PlatformError* error);
  102.     // Delete a range of bytes from the string.
  103.  
  104. FW_ByteCount    FW_PrivString_GetByteLength(FW_HString self);
  105.     // Returns the number of bytes holding character codes (not the number of characters!)
  106.  
  107. FW_ByteCount  FW_PrivString_GetCapacity(FW_HString self);
  108.     // Returns the current capacity for bytes, which may be expanded using SetCapacity
  109.  
  110. FW_CharacterCount    FW_PrivString_GetCharacterLength(FW_HString self, FW_PlatformError* error);
  111.     // Returns the number of characters in the string.
  112.     // For some character sets this may be relatively expensive!
  113.     // For efficiency, if GetByteLength will suffice, use it.
  114.  
  115. FW_HString FW_PrivString_SetCapacity(FW_HString self, long newCapacity);
  116.     // Sets the new capacity, which is the largest number of bytes
  117.     // that may be used for holding character codes.
  118.     
  119. ODIText*    FW_PrivString_RevealODIText(FW_HString self);
  120.     // Reveals the ODIText data structure.
  121.     // This function is provided to make it efficient to pass
  122.     // strings to OpenDoc APIs that are defined with "in ODIText"
  123.     // parameters.  Clients must not modify the revealed ODIText
  124.     // data structure, or all hell may break loose. ;>
  125.     
  126. const char*    FW_PrivString_RevealBuffer(FW_HString self);
  127.     // Reveals the character buffer.
  128.     // This function is provided to make it efficient to directly
  129.     // process the bytes of storage.  Clients must not modify the revealed buffer,
  130.     // or all hell may break loose. ;>
  131.     // NOTE: the buffer is probably NOT nul-terminated!!
  132.  
  133. void FW_PrivString_GetLocale(FW_HString self, FW_Locale* locale);
  134.     // Return this string's locale.
  135.     
  136. FW_HString FW_PrivString_Truncate(FW_HString self, 
  137.                                 FW_BytePosition bytePosition, 
  138.                                 FW_PlatformError* error);
  139.     // Removes the given run of bytes from the current contents.
  140.     // It is the client's responsiblity to insure that no double byte characters
  141.     // are broken!
  142.     
  143. //----------------------------------------------------------------------------------------
  144. //    Insert Functions
  145. //----------------------------------------------------------------------------------------
  146.  
  147. FW_HString FW_PrivString_InsertBytes(FW_HString self, 
  148.                                 const char* bytes, 
  149.                                 FW_ByteCount numberBytes,  
  150.                                 FW_BytePosition position, 
  151.                                 FW_PlatformError* error);
  152.     // Inserts the given bytes at the given byte position.
  153.     // It is the client's responsiblity to insure that bytePosition does not
  154.     // split a double byte character! Hint: bytePosition should have been determined
  155.     // using a function known to return valid character offsets.
  156.  
  157. FW_HString FW_PrivString_InsertODIText(FW_HString self, 
  158.                                 ODIText* text,
  159.                                 FW_BytePosition position, 
  160.                                 FW_PlatformError* error);
  161.     // Inserts the given text at the given byte position.
  162.     // It is the client's responsiblity to insure that bytePosition does not
  163.     // split a double byte character!
  164.  
  165. FW_HString FW_PrivString_InsertStringRep(FW_HString self, 
  166.                                 FW_HString other, 
  167.                                 FW_BytePosition position, 
  168.                                 FW_PlatformError* error);
  169.     // Inserts the given text at the given byte position.
  170.     // It is the client's responsiblity to insure that bytePosition does not
  171.     // split a double byte character!
  172.  
  173. //----------------------------------------------------------------------------------------
  174. //    Replace Functions
  175. //----------------------------------------------------------------------------------------
  176.  
  177. FW_HString FW_PrivString_ReplaceAllStringRep(FW_HString self, 
  178.                                         FW_HString text, 
  179.                                         FW_PlatformError* error);
  180.     // Replaces the current contents with the given text.
  181.  
  182. FW_HString FW_PrivString_ReplaceAllODIText(FW_HString self, 
  183.                                         ODIText* text, 
  184.                                         FW_PlatformError* error);
  185.     // Replaces the current contents with the given text.
  186.  
  187. FW_HString FW_PrivString_ReplaceAllBytes(FW_HString self, 
  188.                                         const char* bytes, 
  189.                                         FW_ByteCount numberBytes, 
  190.                                         FW_PlatformError* error);
  191.     // Replaces the current contents with the given text.
  192.  
  193. //----------------------------------------------------------------------------------------
  194. //    Append Functions
  195. //----------------------------------------------------------------------------------------
  196.  
  197. FW_HString FW_PrivString_AppendODIText(FW_HString self, 
  198.                                         ODIText* text, 
  199.                                         FW_PlatformError* error);
  200.     // Appends the given text onto the end of the current contents.
  201.  
  202. FW_HString FW_PrivString_AppendStringRep(FW_HString self, 
  203.                                         FW_HString text, 
  204.                                         FW_PlatformError* error);
  205.     // Appends the given text onto the end of the current contents.
  206.  
  207. FW_HString FW_PrivString_AppendBytes(FW_HString self, 
  208.                                     const char* bytes, 
  209.                                     FW_ByteCount numberBytes, 
  210.                                     FW_PlatformError* error);
  211.     // Appends the given bytes onto the end of the current contents.
  212.  
  213. //----------------------------------------------------------------------------------------
  214. //    Prepend Functions
  215. //----------------------------------------------------------------------------------------
  216.  
  217. FW_HString FW_PrivString_PrependODIText(FW_HString self, 
  218.                                         ODIText* text, 
  219.                                         FW_PlatformError* error);
  220.     // Prepends the given text onto the beginning of the current contents.
  221.  
  222. FW_HString FW_PrivString_PrependStringRep(FW_HString self, 
  223.                                         FW_HString text, 
  224.                                         FW_PlatformError* error);
  225.     // Prepends the given text onto the beginning of the current contents.
  226.  
  227. FW_HString FW_PrivString_PrependBytes(FW_HString self, 
  228.                                     const char* bytes, 
  229.                                     FW_ByteCount numberBytes, 
  230.                                     FW_PlatformError* error);
  231.     // Prepends the given bytes onto the beginning of the current contents.
  232.  
  233. //----------------------------------------------------------------------------------------
  234. //    Export Functions
  235. //----------------------------------------------------------------------------------------
  236.  
  237. void FW_PrivString_ExportCString(FW_HString self, char* buffer);
  238.     // Copy contents of this string to external buffer as a NUL-terminated C string.
  239.  
  240. void FW_PrivString_ExportPascalString(FW_HString self, FW_PascalChar* buffer);
  241.     // Copy contents of this string to external 'Pascal' buffer.
  242.  
  243. //----------------------------------------------------------------------------------------
  244. //    Monocasing Functions
  245. //----------------------------------------------------------------------------------------
  246.  
  247. FW_HString FW_PrivString_ToUpper(FW_HString self, FW_PlatformError* error);
  248.     // Convert all lowercase characters to uppercase.
  249.  
  250. FW_HString FW_PrivString_ToLower(FW_HString self, FW_PlatformError* error);
  251.     // Convert all uppercase characters to lowercase.
  252.  
  253. //----------------------------------------------------------------------------------------
  254. //    Searching and Substitution Functions
  255. //----------------------------------------------------------------------------------------
  256.  
  257. FW_Boolean FW_PrivString_FindCharacter(FW_HString self, 
  258.                         FW_LChar character, 
  259.                         FW_ByteCount *foundPosition, 
  260.                         FW_ByteCount startPosition,
  261.                         FW_FindDirection direction);
  262.     // Find the first occurence of character, starting the search at startPosition.
  263.     // Return false if the character is not found.
  264.  
  265. FW_Boolean FW_PrivString_FindSubString(FW_HString self, 
  266.                         FW_HString subString, 
  267.                         FW_ByteCount *foundPosition, 
  268.                         FW_ByteCount startPosition);
  269.     // Find the first occurence of substring, starting the search at startPosition.
  270.     // Return false if the substring is not found.
  271.  
  272. FW_HString FW_PrivString_Substitute(FW_HString self, 
  273.                         FW_HString searchString, 
  274.                         FW_HString substitutionString, 
  275.                         FW_Boolean* wasReplaced, 
  276.                         FW_PlatformError* error);
  277.     // Find the first occurence of substring, starting the search at startPosition.
  278.     // If the substring is found, replace it with the substitution string.
  279.     // Set wasReplace to false if the substring was not found.
  280.  
  281. FW_StringCompareResult FW_PrivString_Compare(FW_HString string1, FW_HString string2);
  282.     // Compare the two strings (taking into account locality of the strings).
  283.  
  284. //----------------------------------------------------------------------------------------
  285. //    Number Conversion Functions
  286. //----------------------------------------------------------------------------------------
  287.  
  288. FW_HString FW_PrivString_SignedIntegerToDecimalString(FW_HString self, 
  289.                                                     long integer, 
  290.                                                     FW_PlatformError* error);
  291.     // Given a signed long integer, create a string with it's decimal representation
  292.  
  293. FW_HString FW_PrivString_UnsignedIntegerToDecimalString(FW_HString self, 
  294.                                                     unsigned long integer, 
  295.                                                     FW_PlatformError* error);
  296.     // Given a unsigned long integer, create a string with it's decimal representation
  297.  
  298. FW_HString FW_PrivString_UnsignedIntegerToHexadecimalString(FW_HString self, 
  299.                                                     unsigned long integer, 
  300.                                                     FW_PlatformError* error);
  301.     // Given a unsigned long integer, create a string with it's hexadecimal representation.
  302.     // The uppercase letters A-F are used.
  303.  
  304. long FW_PrivString_DecimalStringToSignedInteger(FW_HString self);
  305.     // Given a string, return the integer.
  306.     // Assumes the string contains a valid decimal representation.
  307.     // The string is parsed to the first non-decimal character (including '-').
  308.     // Zero is returned if the first character is not a decimal character.
  309.     // No error is returned under any condition. 
  310.  
  311. unsigned long FW_PrivString_DecimalStringToUnsignedInteger(FW_HString self);
  312.     // Given a string, return the unsigned integer.
  313.     // Assumes the string contains a valid decimal representation.
  314.     // The string is parsed to the first non-decimal character (not including '-').
  315.     // Zero is returned if the first character is not a decimal character.
  316.     // No error is returned under any condition.
  317.  
  318. unsigned long FW_PrivString_HexadecimalStringToUnsignedInteger(FW_HString self);
  319.     // Given a string, return the unsigned integer.
  320.     // Assumes the string contains a valid hexadecimal representation.
  321.     // The string is parsed to the first non-hexadecimal character
  322.     // (including a-f, A-F, not including '-').
  323.     // Zero is returned if the first character is not a decimal character.
  324.     // No error is returned under any condition.
  325.  
  326. FW_HString FW_PrivString_DoubleToString(FW_HString self, 
  327.                                         double value, 
  328.                                         short fractionalDigits,
  329.                                         FW_PlatformError* error);
  330.     // Given a floating point value, create a string with it's decimal representation
  331.     // fractionalDigits is the number of digits to be shown after the decimal point.
  332.     // All digits to the left of the decimal point are shown (sci notation is never used).  
  333.  
  334. double FW_PrivString_StringToDouble(FW_HString self);
  335.     // Given a string, return the double.
  336.     // Assumes the string contains a valid floating point representation.
  337.     // Zero is returned if the first character is not a decimal character (include '-').
  338.     // No error is returned under any condition.
  339.  
  340. FW_EXTERN_C_END
  341.  
  342. // For CFM-68K [sfu]
  343.  
  344. #if defined(FW_ODFLIB_IMPORT)
  345. #pragma import off
  346. #elif defined(FW_ODFLIB)
  347. #pragma export off
  348. #endif
  349.  
  350. #endif
  351.  
  352.